[MDX Blog](/blog)

> [ZEIT is now Vercel](https://rauchg.com/2020/vercel).
> The below is kept as is for historical purposes.

# MDX goes stable

It’s been a year and a half since the first MDX commit and a year since MDX was first announced at
ZEIT Day. MDX is a radical paradigm shift in how to write immersive content using components. It’s
an open, [authorable format](https://johno.com/authorable-format) that makes it _fun_ to write again.

Since announcing MDX we’ve been working on numerous bug fixes, new features, better parsing, and integration
tests. Now, we think it’s ready. **We’re happy to finally release v1!**

## 🎉 What’s new?

Here’s a rough breakdown on what we’ve been working on:

### Parsing

MDX document parsing is significantly improved.
We won’t get into the nitty gritty here, but we’ve seen how MDX is used in real-world projects, integrated
the edge cases we came across into our test suite, and now handle JSX, imports, and exports much more
intuitively.
Please open an issue if you find a case we haven’t covered! 😸

### remark-mdx

`remark-mdx` is the syntactic extension for MDX in remark. It provides the parsing functionality for
MDX as a _[remark](https://github.com/remarkjs/remark) plugin_. That sounds a bit meta. What it means
is that before we had the syntax parsing bits _in_ the library (unusable from the outside), and now it’s
externalized (usable from the outside). This is useful if you want to inspect or transform MDX documents.
For example, it allows tools like prettier to use the exact same parser used by MDX core. Or you could
use `remark-mdx` in combination with [remark-lint](https://github.com/remarkjs/remark-lint) to check your
MDX.

### Custom pragma

With v1 we’ve moved away from using `MDXTag` and are using a custom pragma which wraps `React.createElement`.
We decided to update this approach so the JSX output is more legible, lighterweight, and more customizable.
**This means MDX can be used with any React, Vue, Preact, or any other library with JSX support**.

Special thanks to [@christopherbiscardi](https://github.com/christopherbiscardi) for implementing this feature.

[Read the blog post](/blog/custom-pragma)

### 📚 Documentation

**Good libraries need great docs**, so we’ve been working on adding content and improving the overall documentation
website experience.

- [Search (thanks Algolia)](https://mobile.twitter.com/4lpine/status/1114270174096412672)
- [Guides](https://mdxjs.com)
- [Automatic deployment via ZEIT](https://zeit.co)
- [Custom Gatsby theme](https://gatsbyjs.org)
- Reorganization of docs for intuitiveness
- Full page rewrites to improve clarity

Special thanks to [@jxnblk](https://github.com/jxnblks) and [@wooorm](https://github.com/wooorm) for their help
improving the docs and updating the build tooling.

## Breaking changes

In order to make some improvements we were forced to introduce a few breaking changes. **These were the
result of real-world production testing and feedback**. The community has evolved and we’ve come up with
newer, better ideas over the last year. We have made sure the impact is small and have written a full
migration guide.

- 🚨`@mdx-js/tag` is replaced by `@mdx-js/react` and an `@mdx` pragma - [migration guide](/migrating/v1#pragma)
- MDXProvider now merges component contexts when nested - [migration guide](/migrating/v1#mdxprovider)
- React support now requires `>= 16.8` in `@mdx-js/react` - [migration guide](/migrating/v1#react)

[Read the full v1 migration guide](/migrating/v1)

#### Deprecations

We only needed to introduce one deprecation. The `mdPlugins` and `hastPlugins` options have been renamed
`remarkPlugins` and `rehypePlugins` respectively. For the time being we will issue a warning when the old options
are used. In v2, the old options will be removed.

## 📈 Growth

A major release is always a good time to take a step back and reflect on what’s been happening in terms of growth
and the greater community. The ecosystem surrounding MDX has already grown larger than we ever dreamed. We’ve also
seen projects/products/application we never even imagined.

### Numbers

- **Downloads**: 125,000/week, 2.4M total
- **Stars**: 6,200
- **Contributors**: 50
- **Pull requests**: 281
- **Commits**: 670

The contributor growth is one of the most important aspects here as we have numerous community members that are familiar
with MDX internals. This allows us to continually improve the project and spread the workload against an ever growing
team of contributors.

[See the contributor graph](https://github.com/mdx-js/mdx/graphs/contributors)

### Ecosystem

- [Prettier](https://prettier.io)
- [Docz](https://docz.site)
- [MDX Deck](https://github.com/jxnblk/mdx-deck)
- [Next.js](https://nextjs.org)
- [Gatsby](https://gatsbyjs.org)
- [AST Explorer](https://astexplorer.net)
- [Vue support (alpha)](/vue)
- [Demoboard](https://frontarm.com/demoboard/)
- [Editors](/editors)

## 🛣 Roadmap

With v1 released we have a roadmap in place that we’ll continue working towards over the next 6 months or
so in addition to bug fixes and parsing issues we might encounter.

- MDXs: [#454](https://github.com/mdx-js/mdx/issues/454)
- Interleaving: [#195](https://github.com/mdx-js/mdx/issues/195)
- Global shortcodes: [#508](https://github.com/mdx-js/mdx/pull/508)
- Stable Vue support: [#238](https://github.com/mdx-js/mdx/issues/238)
- Blocks: MDX WYSIWYG: [blocks/blocks](https://github.com/blocks/blocks)
- MDX playground inspired by AST Explorer: [#220](https://github.com/mdx-js/mdx/issues/220)
- New splash page: [#444](https://github.com/mdx-js/mdx/issues/444)
- Showcase page: [#414](https://github.com/mdx-js/mdx/issues/414)

### Vue support

Supporting Vue is an important goal for MDX and is one of the primary reasons we’ve rearchitected MDX to use
custom pragma. We’re delighted that **we now have an alpha version for Vue working**. We’d love it if anyone
from the Vue community wants to give it a try and provide feedback.

[See the Vue example](https://github.com/mdx-js/mdx/tree/master/examples/vue)

### Blocks project

One of the key missing aspects of authoring MDX documents is the editing experience. Currently, there isn’t an
approachable way to write MDX unless you enjoy working in a text editor and writing raw Markdown/code. We’d
like to solve that and have begun work on an MDX “blocks editor” that’s a **content-focused WYSIWYG**. Not to mention,
we’ll be doing all that we can to make sure the editor is as accessible as it can be from the beginning.

When we have a beta ready we will be open sourcing it and announcing, so stay tuned.

[Check out the Blocks project](https://github.com/blocks/blocks)

## unified collective

MDX is part of the unified collective, which is an open source ecosystem for dealing with many sources of content. unified
projects are used all over the web, and it would never be possible without financial support from our fine sponsors.

- [ZEIT](https://zeit.co) 🥇
- [Gatsby](https://gatsbyjs.org) 🥇
- [Holloway](https://www.holloway.com) 🥉
- [Backers](https://opencollective.com/unified#budget) 🏆
- [You?](https://opencollective.com/unified) 👤

## 🙏 Thanks

We’d like to say thanks to all our contributors and our happy users. Special thanks to
[@wooorm](https://github.com/wooorm),
[@silvenon](https://github.com/silvenon),
[@timneutkens](https://github.com/timneutkens),
[@ChristopherBiscardi](https://github.com/christopherbiscardi),
[@jxnblk](https://github.com/jxnblk),
[@alexandernanberg](https://github.com/alexandernanberg),
[@jescalan](https://github.com/jescalan),
[@Jarred-Sumner](https://github.com/Jarred-Sumner),
[@leimonio](https://github.com/leimonio),
[@ticky](https://github.com/ticky),
[@jamesknelson](https://github.com/jamesknelson),
[@pshrmn](https://github.com/pshrmn),
[@rauchg](https://github.com/rauchg),
[@joelhooks](https://github.com/joelhooks),
[@jlengstorf](https://github.com/jlengstorf),
[@johnlindquist](https://github.com/johnlindquist),
[@kyleamathews](https://github.com/kyleamathews),
[@kentcdodds](https://github.com/kentcdodds),
[@wesbos](https://github.com/wesbos),
[@rosew](https://github.com/rosew),
[@pedronauck](https://github.com/pedronauck),
[@tayiorbeii](https://github.com/tayiorbeii),
[@nickbender](https://github.com/nickbender),
[@ntaylor89](https://github.com/ntaylor89),
[@mxstbr](https://github.com/mxstbr),
[@manovotny](https://github.com/manovotny),
[@xyc](https://github.com/xyc),
[@filoxo](https://github.com/filoxo),
[@millette](https://github.com/millette),
[@hugmanrique](https://github.com/hugmanrique),
[@johnsherrard](https://github.com/johnsherrard),
[@sw-yx](https://github.com/sw-yx),
and anyone we may have forgotten.

---

Written by [John Otander](https://johno.com)

**[&lt; Back to blog](/blog)**
